.\" Copyright (c) 2014-2020 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 12, 2014
.Dt AG_STYLESHEET 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.5
.Sh NAME
.Nm AG_StyleSheet
.Nd agar cascading style sheets
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" MANLINK(AG_Style)
.\" IMAGE(http://libagar.org/widgets/AG_Style.png, "Alternate style sheet")
The graphical appearance (typography, colors, paddings and spacings) of Agar
widgets is controlled by the style engine.
Style properties can be either applied to individual widgets with
.Xr AG_SetStyle 3
or defined as part of blocks of attributes in an Agar stylesheet.
.Pp
The
.Nm
language makes no attempt at compatibility with HTML CSS (GUI elements are not
DOM-oriented), but we've adopted some of its syntax and keywords
in order to ease the learning curve for new users.
.Pp
Note: The rendering code of Agar widgets has no conception of style attributes.
It uses a compact binary representation generated by the style compiler,
which itself runs on demand only when properties are changed.
.Sh TYPOGRAPHY
Typographical style attributes include:
.Pp
.Bl -tag -compact -width "font-stretch "
.It Va font-family
"Courier", "DejaVu Sans", "foo.woff2", "my.bmp"
.It Va font-size
"10pts", "10.5pts", "80%"
.It Va font-weight
"normal", "bold" or "!parent"
.It Va font-style
"normal", "italic", "upright-italic" or "!parent"
.It Va font-stretch
"normal", "condensed", "semi-condensed" or "!parent"
.El
.Pp
The
.Va font-family
attribute selects the type face.
Agar will scan system fonts (via fontconfig), Agar core fonts as well as
user-installed fonts (according to the FONT_PATH setting of
.Xr AG_Config 3 ) .
Matching is case-insensitive with fontconfig but case-sensitive with core
and user fonts.
.Pp
.Va font-size
sets the font size either in points ("10pts", "10.5pts") or in
percentage of the parent font size ("80%").
In general font sizes should be specified in "%" so that
.Xr AG_ZoomIn 3
and
.Xr AG_ZoomOut 3
(which trivially sets "font-size" on the window) may work as expected.
.Pp
.Va font-weight
sets the font weight to "normal", "bold" (bold variant)
or "!parent" (opposite of parent's setting).
.Pp
.Va font-style
sets the font style to "normal", "italic" (italic / oblique), "upright-italic"
or "!parent" (opposite of parent's setting).
.Pp
.Va font-stretch
sets the width variant of the font to "normal", "semi-condensed", "condensed"
or "!parent" (opposite of parent's setting).
.Sh COLORS
Color-defining style attributes include:
.Pp
.Bl -tag -compact -width "background-color "
.It Va color
Foreground primary
.It Va background-color
Background primary
.It Va text-color
Text and vector icons
.It Va line-color
Lines and filled shapes
.It Va high-color
Shading (top and left)
.It Va low-color
Shading (bottom and right)
.It Va selection-color
Selection primary
.El
.Pp
Colors allow an optional state selector (e.g., "color#focused").
If no selector is given then the given color is assigned to all states.
.Pp
.Bl -tag -compact -width "#unfocused "
.It "#unfocused"
Widget is not focused (default state).
.It "#focused"
Widget is focused (see
.Xr AG_WidgetFocus 3 ) .
.It "#disabled"
Widget is disabled (see
.Xr AG_WidgetDisable 3 ) .
.It "#hover"
Cursor is over the widget (MOUSEOVER is set).
.El
.Pp
Color values can be specified using any one of the representations below.
See
.Xr AG_ColorFromString 3
for details.
.Pp
.Bl -tag -width "Real hue/saturation/value " -compact
.It "8-bit Device RGB"
"r,g,b[,a]" or "rgb(r,g,b[,a])"
.It "16-bit Device RGB"
"rgb16(r,g,b[,a])"
.It "Hue, Saturation and Value"
"hsv(h,s,v[,a])"
.It "16-bit hex"
"#rgb[a]"
.It "32-bit hex"
"#rrggbb[aa]"
.It "64-bit hex"
"#rrrrggggbbbb[aaaa]"
.It "Color keyword"
"AliceBlue", "antiquewhite"
.El
.Pp
RGBA and HSV components may be expressed in "%" (in relation to the
same color entry in the parent widget's palette).
.Pp
Color keywords are matched case-insensitively.
.Sh PADDING AND SPACING
Paddings and spacings are specified in pixels:
.Pp
.Bl -tag -compact -width "padding "
.It Va padding
"<Number>", "<T> <R> <B> <L>" or "inherit"
.It Va spacing
"<Number>", "<H> <V>" or "inherit"
.El
.Pp
When
.Va padding
is given as a single number, it applies to all (Top, Right, Bottom and Left)
sides.
If
.Va spacing
is a single number, both horizontal and vertical spacings are set.
.Pp
Different widget classes will handle padding and spacing differently.
Some widgets can handle negative padding and negative spacing values
(as a way to indicate condensing of separated items or features).
.Sh INITIALIZATION
.nr nS 1
.Ft "void"
.Fn AG_InitStyleSheet "AG_StyleSheet *ss"
.Pp
.Ft "void"
.Fn AG_DestroyStyleSheet "AG_StyleSheet *css"
.Pp
.Ft "AG_StyleSheet *"
.Fn AG_LoadStyleSheet "void *obj" "const char *path"
.Pp
.Ft int
.Fn AG_LookupStyleSheet "AG_StyleSheet *css" "void *widget" "const char *key" "char **rv"
.nr nS 0
.Pp
The
.Fn AG_InitStyleSheet
function initializes the given
.Nm
as an empty style sheet.
.Fn AG_DestroyStyleSheet
releases all resources allocated by a style sheet.
.Pp
The
.Fn AG_LoadStyleSheet
function loads a style sheet from
.Fa path .
On success, a newly allocated
.Nm
is returned.
If
.Fa path
begins with a "_" character,
.Fn AG_LoadStyleSheet
will search for a statically-compiled stylesheet
(i.e., "_agStyleDefault" is always available).
.Pp
The
.Fn AG_LookupStyleSheet
routine searches the style sheet for the specified attribute
(identified by
.Fa key ) .
If the style sheet defines an attribute applicable to the specified widget
instance (the
.Fa widget
argument), its value is returned into
.Fa rv .
.Sh EXAMPLES
Agar's default stylesheet is compiled from
.Pa gui/style.css .
It is a good starting point for writing new stylesheets.
.Pp
The stylesheet fragment selects a condensed font, tweaks the color scheme
and sets padding values for the
.Xr AG_Button 3
class:
.Bd -literal
AG_Button {
	font-family: league-gothic;
	font-stretch: condensed;
	font-size: 120%;

	color: AntiqueWhite;
	text-color: #000;

	color#disabled: rgb(200,200,200);
	text-color#disabled: rgb(125,125,125);

	high-color#hover: red;
	low-color#hover: darkred;

	padding: 5 4 5 4;      /* TRBL */
}
.Ed
.Pp
By default, a widget instance inherits its style attributes from its parent.
The syntax allows certain attributes, such as "font-size" and "color" to
be specified in relation to the parent.
For example:
.Bd -literal
	font-size: 50%;			# Half of parent font size
	color: hsv(100%,50%,100%);	# Half of parent saturation
	color: hsv(100%,100%,75%);	# 3/4 of parent value
.Ed
.Pp
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
A very basic
.Nm
language first appeared in Agar 1.5.0.
Agar 1.6.0 improved parsing and validation, introduced a new color scheme,
added typography features as well as "padding" and "spacing".
